org.jboss.byteman.agent
Class Transformer

java.lang.Object
  extended by org.jboss.byteman.agent.Transformer
All Implemented Interfaces:
java.lang.instrument.ClassFileTransformer
Direct Known Subclasses:
Retransformer

public class Transformer
extends java.lang.Object
implements java.lang.instrument.ClassFileTransformer

byte code transformer used to introduce byteman events into JBoss code


Field Summary
static java.lang.String ALLOW_CONFIG_UPDATE
          system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listener
static java.lang.String BYTEMAN_PACKAGE_PREFIX
          prefix for byteman package
static java.lang.String BYTEMAN_SAMPLE_PACKAGE_PREFIX
          prefix for byteman sample package
static java.lang.String BYTEMAN_TEST_PACKAGE_PREFIX
          prefix for byteman test package
static java.lang.String COMPILE_TO_BYTECODE
          system property set (to any value) in order to switch on compilation of rules and left unset if rules are to be interpreted.
static java.lang.String COMPILE_TO_BYTECODE_COMPATIBILITY
          retained for compatibility
static java.lang.String DEBUG
          system property set (to any value) in order to switch on debug statements in the default Helper
static java.lang.String DUMP_CFG
          system property set (to any value) in order to switch on dumping of control flow graph for triger method after construction
static java.lang.String DUMP_CFG_PARTIAL
          system property set (to any value) in order to switch on dumping of control flow graph for trigger method at each stage of construction
static java.lang.String DUMP_GENERATED_CLASSES
          system property set (to any value) in order to switch on dumping of generated bytecode to .class files
static java.lang.String DUMP_GENERATED_CLASSES_DIR
          system property identifying directory in which to dump generated bytecode .class files
static java.lang.String DUMP_GENERATED_CLASSES_INTERMEDIATE
          system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class files
protected  HelperManager helperManager
          a manager for helper lifecycle events which can be safely handed on to rules
protected  java.lang.instrument.Instrumentation inst
          the instrumentation interface to the JVM
protected  boolean isRedefine
          true if the instrumentor allows redefinition
static java.lang.String JAVA_LANG_PACKAGE_PREFIX
          prefix for org.jboss package
protected  LoadCache loadCache
          a cache tracking which classes have been loaded by which class loaders which is used when attempting to resolve a superName to a superclass.
protected  ScriptRepository scriptRepository
          a mapping from target class names which appear in rules to a script object holding the rule details
static java.lang.String SKIP_OVERRIDE_RULES
          system property which turns off injection into overriding methods
static java.lang.String SYSPROPS_STRICT_MODE
          system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.
static java.lang.String TRANSFORM_ALL
          system property set to true in order to enable transform of java.lang classes
static java.lang.String TRANSFORM_ALL_COMPATIBILITY
          retained for compatibility
static java.lang.String VERBOSE
          system property set (to any value) in order to switch on dumping of generated bytecode to .class files
static java.lang.String VERIFY_TRANSFORMED_BYTES
          system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.
 
Constructor Summary
Transformer(java.lang.instrument.Instrumentation inst, java.util.List<java.lang.String> scriptPaths, java.util.List<java.lang.String> scriptTexts, boolean isRedefine)
          constructor allowing this transformer to be provided with access to the JVM's instrumentation implementation
 
Method Summary
static boolean allowConfigUpdate()
          check whether changes to org.jboss.byteman.* system properties will affect the agent configuration.
static boolean computeDumpGeneratedClasses()
           
static java.lang.String computeDumpGeneratedClassesDir()
           
static boolean computeDumpGeneratedClassesIntermediate()
           
static boolean disableTriggers(boolean isUser)
          disable triggering of rules inside the current thread
protected  void dumpScript(RuleScript ruleScript)
           
static boolean enableTriggers(boolean isReset)
          enable triggering of rules inside the current thread
 void installBootScripts()
          ensure that scripts which apply to classes loaded before registering the transformer get are installed by retransforming the relevant classes
protected  boolean isBytemanClass(java.lang.String className)
          test whether a class with a given name is located in the byteman package
static boolean isCompileToBytecode()
          check whether compilation of rules is enabled or disabled
static boolean isDebug()
          check whether debug mode for rule processing is enabled or disabled
static boolean isDumpCFG()
          check whether dumping of the control flow graph for the trigger class is enabled
static boolean isDumpCFGPartial()
          check whether dumping of the control flow graph for the trigger class during construction is enabled
protected  boolean isSkipClass(java.lang.Class<?> clazz)
          check whether a class should not be considered for transformation
protected  boolean isTransformable(java.lang.String className)
          test whether a class with a given name is a potential candidate for insertion of event notifications
static boolean isTriggeringEnabled()
          check if triggering of rules is enabled inside the current thread
static boolean isVerbose()
          check whether verbose mode for rule processing is enabled or disabled
static void maybeDumpClass(java.lang.String fullName, byte[] bytes)
           
static void maybeDumpClassIntermediate(java.lang.String fullName, byte[] bytes)
           
 boolean skipOverrideRules()
          check whether compilation of rules is enabled or disabled
 byte[] transform(java.lang.ClassLoader originalLoader, java.lang.String className, java.lang.Class<?> classBeingRedefined, java.security.ProtectionDomain protectionDomain, byte[] classfileBuffer)
          The implementation of this method may transform the supplied class file and return a new replacement class file.
 byte[] transform(RuleScript ruleScript, java.lang.ClassLoader loader, java.lang.String className, byte[] targetClassBytes)
          The routine which actually does the real bytecode transformation.
 void updateConfiguration(java.lang.String property)
          notify a change to an org.jboss.byteman.* system property so that the agent can choose to update its configuration.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BYTEMAN_PACKAGE_PREFIX

public static final java.lang.String BYTEMAN_PACKAGE_PREFIX
prefix for byteman package

See Also:
Constant Field Values

BYTEMAN_TEST_PACKAGE_PREFIX

public static final java.lang.String BYTEMAN_TEST_PACKAGE_PREFIX
prefix for byteman test package

See Also:
Constant Field Values

BYTEMAN_SAMPLE_PACKAGE_PREFIX

public static final java.lang.String BYTEMAN_SAMPLE_PACKAGE_PREFIX
prefix for byteman sample package

See Also:
Constant Field Values

JAVA_LANG_PACKAGE_PREFIX

public static final java.lang.String JAVA_LANG_PACKAGE_PREFIX
prefix for org.jboss package

See Also:
Constant Field Values

VERBOSE

public static final java.lang.String VERBOSE
system property set (to any value) in order to switch on dumping of generated bytecode to .class files

See Also:
Constant Field Values

DUMP_CFG_PARTIAL

public static final java.lang.String DUMP_CFG_PARTIAL
system property set (to any value) in order to switch on dumping of control flow graph for trigger method at each stage of construction

See Also:
Constant Field Values

DUMP_CFG

public static final java.lang.String DUMP_CFG
system property set (to any value) in order to switch on dumping of control flow graph for triger method after construction

See Also:
Constant Field Values

DEBUG

public static final java.lang.String DEBUG
system property set (to any value) in order to switch on debug statements in the default Helper

See Also:
Constant Field Values

COMPILE_TO_BYTECODE_COMPATIBILITY

public static final java.lang.String COMPILE_TO_BYTECODE_COMPATIBILITY
retained for compatibility

See Also:
Constant Field Values

COMPILE_TO_BYTECODE

public static final java.lang.String COMPILE_TO_BYTECODE
system property set (to any value) in order to switch on compilation of rules and left unset if rules are to be interpreted.

See Also:
Constant Field Values

DUMP_GENERATED_CLASSES

public static final java.lang.String DUMP_GENERATED_CLASSES
system property set (to any value) in order to switch on dumping of generated bytecode to .class files

See Also:
Constant Field Values

DUMP_GENERATED_CLASSES_INTERMEDIATE

public static final java.lang.String DUMP_GENERATED_CLASSES_INTERMEDIATE
system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class files

See Also:
Constant Field Values

DUMP_GENERATED_CLASSES_DIR

public static final java.lang.String DUMP_GENERATED_CLASSES_DIR
system property identifying directory in which to dump generated bytecode .class files

See Also:
Constant Field Values

TRANSFORM_ALL

public static final java.lang.String TRANSFORM_ALL
system property set to true in order to enable transform of java.lang classes

See Also:
Constant Field Values

TRANSFORM_ALL_COMPATIBILITY

public static final java.lang.String TRANSFORM_ALL_COMPATIBILITY
retained for compatibility

See Also:
Constant Field Values

SKIP_OVERRIDE_RULES

public static final java.lang.String SKIP_OVERRIDE_RULES
system property which turns off injection into overriding methods

See Also:
Constant Field Values

SYSPROPS_STRICT_MODE

public static final java.lang.String SYSPROPS_STRICT_MODE
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.

See Also:
Constant Field Values

VERIFY_TRANSFORMED_BYTES

public static final java.lang.String VERIFY_TRANSFORMED_BYTES
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.

See Also:
Constant Field Values

ALLOW_CONFIG_UPDATE

public static final java.lang.String ALLOW_CONFIG_UPDATE
system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listener

See Also:
Constant Field Values

inst

protected final java.lang.instrument.Instrumentation inst
the instrumentation interface to the JVM


isRedefine

protected boolean isRedefine
true if the instrumentor allows redefinition


scriptRepository

protected final ScriptRepository scriptRepository
a mapping from target class names which appear in rules to a script object holding the rule details


loadCache

protected final LoadCache loadCache
a cache tracking which classes have been loaded by which class loaders which is used when attempting to resolve a superName to a superclass.


helperManager

protected final HelperManager helperManager
a manager for helper lifecycle events which can be safely handed on to rules

Constructor Detail

Transformer

public Transformer(java.lang.instrument.Instrumentation inst,
                   java.util.List<java.lang.String> scriptPaths,
                   java.util.List<java.lang.String> scriptTexts,
                   boolean isRedefine)
            throws java.lang.Exception
constructor allowing this transformer to be provided with access to the JVM's instrumentation implementation

Parameters:
inst - the instrumentation object used to interface to the JVM
Throws:
java.lang.Exception
Method Detail

installBootScripts

public void installBootScripts()
                        throws java.lang.Exception
ensure that scripts which apply to classes loaded before registering the transformer get are installed by retransforming the relevant classes

Throws:
java.lang.Exception

transform

public byte[] transform(java.lang.ClassLoader originalLoader,
                        java.lang.String className,
                        java.lang.Class<?> classBeingRedefined,
                        java.security.ProtectionDomain protectionDomain,
                        byte[] classfileBuffer)
                 throws java.lang.instrument.IllegalClassFormatException
The implementation of this method may transform the supplied class file and return a new replacement class file.

Once a transformer has been registered with Instrumentation.addTransformer, the transformer will be called for every new class definition and every class redefinition. The request for a new class definition is made with ClassLoader.defineClass. The request for a class redefinition is made with Instrumentation.redefineClasses or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied.

If the implementing method determines that no transformations are needed, it should return null. Otherwise, it should create a new byte[] array, copy the input classfileBuffer into it, along with all desired transformations, and return the new array. The input classfileBuffer must not be modified.

In the redefine case, the transformer must support the redefinition semantics. If a class that the transformer changed during initial definition is later redefined, the transformer must insure that the second class output class file is a legal redefinition of the first output class file.

If the transformer believes the classFileBuffer does not represent a validly formatted class file, it should throw an IllegalClassFormatException. Subsequent transformers will still be called and the load or redefine will still be attempted. Throwing an IllegalClassFormatException thus has the same effect as returning null but facilitates the logging or debugging of format corruptions.

Specified by:
transform in interface java.lang.instrument.ClassFileTransformer
Parameters:
originalLoader - the defining loader of the class to be transformed, may be null if the bootstrap loader
className - the name of the class in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example, "java/util/List".
classBeingRedefined - if this is a redefine, the class being redefined, otherwise null
protectionDomain - the protection domain of the class being defined or redefined
classfileBuffer - the input byte buffer in class file format - must not be modified
Returns:
a well-formed class file buffer (the result of the transform), or null if no transform is performed.
Throws:
java.lang.instrument.IllegalClassFormatException - if the input does not represent a well-formed class file
See Also:
Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition...)

disableTriggers

public static boolean disableTriggers(boolean isUser)
disable triggering of rules inside the current thread

Returns:
true if triggering was previously enabled and false if it was already disabled

enableTriggers

public static boolean enableTriggers(boolean isReset)
enable triggering of rules inside the current thread

Returns:
true if triggering was previously enabled and false if it was already disabled

isTriggeringEnabled

public static boolean isTriggeringEnabled()
check if triggering of rules is enabled inside the current thread

Returns:
true if triggering is enabled and false if it is disabled

isVerbose

public static boolean isVerbose()
check whether verbose mode for rule processing is enabled or disabled

Returns:
true if verbose mode is enabled etherwise false

isDumpCFG

public static boolean isDumpCFG()
check whether dumping of the control flow graph for the trigger class is enabled

Returns:
true if dumping is enabled etherwise false

isDumpCFGPartial

public static boolean isDumpCFGPartial()
check whether dumping of the control flow graph for the trigger class during construction is enabled

Returns:
true if dumping is enabled etherwise false

isDebug

public static boolean isDebug()
check whether debug mode for rule processing is enabled or disabled

Returns:
true if debug mode is enabled or verbose mode is enabled otherwise false

isCompileToBytecode

public static boolean isCompileToBytecode()
check whether compilation of rules is enabled or disabled

Returns:
true if compilation of rules is enabled etherwise false

skipOverrideRules

public boolean skipOverrideRules()
check whether compilation of rules is enabled or disabled

Returns:
true if compilation of rules is enabled otherwise false

allowConfigUpdate

public static boolean allowConfigUpdate()
check whether changes to org.jboss.byteman.* system properties will affect the agent configuration.

Returns:
true if changes will affect the agent configuration otherwise false

updateConfiguration

public void updateConfiguration(java.lang.String property)
notify a change to an org.jboss.byteman.* system property so that the agent can choose to update its configuration. n.b. this method is not synchronized because there is an implicit assumption that it is called from the the listener thread immediately after it has updated the property and that no other thread will modify org.jboss.byteman.* properties

Parameters:
property - an org.jboss.byteman.* system property which has been updated.

isTransformable

protected boolean isTransformable(java.lang.String className)
test whether a class with a given name is a potential candidate for insertion of event notifications

Parameters:
className -
Returns:
true if a class is a potential candidate for insertion of event notifications otherwise return false

maybeDumpClassIntermediate

public static void maybeDumpClassIntermediate(java.lang.String fullName,
                                              byte[] bytes)

maybeDumpClass

public static void maybeDumpClass(java.lang.String fullName,
                                  byte[] bytes)

transform

public byte[] transform(RuleScript ruleScript,
                        java.lang.ClassLoader loader,
                        java.lang.String className,
                        byte[] targetClassBytes)
The routine which actually does the real bytecode transformation. this is public because it needs to be callable form the type checker script. In normal running the javaagent is the only class which has a handle on the registered transformer so it is the only one which can reach this point.

Parameters:
ruleScript -
loader -
className -
targetClassBytes -
Returns:

isSkipClass

protected boolean isSkipClass(java.lang.Class<?> clazz)
check whether a class should not be considered for transformation

Parameters:
clazz - the class to check
Returns:
true if clazz should not be considered for transformation otherwise false

dumpScript

protected void dumpScript(RuleScript ruleScript)

isBytemanClass

protected boolean isBytemanClass(java.lang.String className)
test whether a class with a given name is located in the byteman package

Parameters:
className -
Returns:
true if a class is located in the byteman package otherwise return false

computeDumpGeneratedClasses

public static boolean computeDumpGeneratedClasses()

computeDumpGeneratedClassesIntermediate

public static boolean computeDumpGeneratedClassesIntermediate()

computeDumpGeneratedClassesDir

public static java.lang.String computeDumpGeneratedClassesDir()


Copyright © 2012. All Rights Reserved.